docs: update comments and README to reflect current feature set

- Refresh app.py module and route docstrings for runtime settings,
  MP3 tagging, rate limiting, revision workflow, and admin actions.
- Clarify config.py and models.py comments.
- Update template comments/CSS for dashboard filters, request detail,
  player page, and settings page.
- Rewrite README.md with current features, status flow, file layout,
  deployment variables, and troubleshooting.
- Refresh REVIEW.md quick-reference.
- Add MAX_REVISIONS to docker-compose.yml environment list.
- Expand requirements.txt comment coverage.

No version history or changelog included.

models.py

@@ -8,7 +8,8 @@ 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, and player token.
+  approval state, email timestamps, payment reference, player token,
+  vocal gender preference, revision count, and revision notes.
 - Indexes on status and player_token for fast queue/lookup.
 """
 
@@ -40,7 +41,7 @@ CREATE TABLE IF NOT EXISTS requests (
     preview_sent_at TIMESTAMP,
     delivery_sent_at TIMESTAMP,
     square_payment_ref TEXT,
-    admin_alert_email TEXT,
+    admin_alert_email TEXT,  -- reserved for future operator alerts; currently unused
     player_token TEXT NOT NULL UNIQUE,
     revision_count INTEGER DEFAULT 0,
     revision_note TEXT
@@ -115,7 +116,9 @@ def get_request_by_token(token):
 
 
 def list_requests(status=None):
-    """List all requests, optionally filtered by status, newest first."""
+    """List all requests, optionally filtered by status, newest first.
+    Normalizes whitespace in the status parameter so URLs like "Needs Upload"
+    match the stored value."""
     db = get_db()
     if status:
         # Translate human filter names to stored status values.
@@ -141,7 +144,8 @@ def update_request(request_id, **fields):
 
 
 def delete_request(request_id):
-    """Delete a single request by id. Does NOT delete associated files."""
+    """Delete a single request row by id. Does NOT delete associated files
+    (the caller in app.py removes uploads before/after this call)."""
     db = get_db()
     db.execute('DELETE FROM requests WHERE id = ?', (request_id,))
     db.commit()