docs: update comments, docstrings, README, REVIEW, and env docs to match current features

models.py

@@ -9,7 +9,11 @@ application context (`g`) is used to manage one connection per request.
 Schema overview (see SCHEMA constant):
 - requests table stores customer data, generated prompts, file paths,
   approval state, email timestamps, payment reference, player token,
-  vocal gender preference, revision count, and revision notes.
+  vocal gender preference, revision count, revision note, and operator notes.
+- Revisions: when a customer requests changes, the current A/B MP3 files are
+  renamed to archived "RevN-" copies and new versions are uploaded later.
+- operator_notes is an internal column for the booth team and is never shown
+  to customers.
 - Indexes on status and player_token for fast queue/lookup.
 """