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

.env.example

@@ -11,12 +11,18 @@
 #   PUBLIC_BASE_URL     - public HTTPS URL customers will use (e.g. https://booth.example.com)
 #
 # Optional:
-#   BOOTH_NAME          - name shown in emails
+#   BOOTH_NAME          - name shown in emails and customer text (default Trollgorithm Theme Songs)
 #   HOST_PORT           - host-side port mapping for docker-compose (default 127.0.0.1:8000)
 #   INTERNAL_PORT       - port gunicorn binds inside the container (default 8000)
 #   PRICE_PER_VERSION   - shown on the receipt page (default 10.00)
 #   CURRENCY            - currency label (default CAD)
-#   ADMIN_ALERT_EMAIL   - unused; dashboard is the operator queue
+#   MAX_REVISIONS       - default customer revision limit (default 2)
+#   DATABASE            - SQLite database path inside the container (default /app/data/booth.db)
+#   UPLOAD_FOLDER       - directory for uploaded MP3s inside the container (default /app/uploads)
+#   SMTP_HOST           - outgoing mail server (default mailroot8.namespro.ca)
+#   SMTP_PORT           - outgoing mail server port (default 465)
+#   SMTP_USER           - SMTP login username (default ai@hallsworth.ca)
+#   SMTP_FROM           - From address for customer emails (default ai@hallsworth.ca)
 
 APP_SECRET_KEY=change-me-in-production
 ADMIN_PASSWORD=change-me
@@ -32,5 +38,6 @@ INTERNAL_PORT=8000
 HOST_PORT=127.0.0.1:8000
 PRICE_PER_VERSION=10.00
 CURRENCY=CAD
+MAX_REVISIONS=2
 DATABASE=/app/data/booth.db
 UPLOAD_FOLDER=/app/uploads

Dockerfile

@@ -10,6 +10,9 @@
 # 4. Copy the entire repo into /app.
 # 5. Create an unprivileged user (boothuser) and data/upload directories.
 # 6. Expose the default internal port and run gunicorn on $INTERNAL_PORT.
+#
+# Environment: expects INTERNAL_PORT (default 8000) and the variables listed
+# in config.py/.env.example to be supplied at runtime by docker-compose.
 
 FROM python:3.12-slim
 

config.py

@@ -3,14 +3,30 @@ config.py
 =========
 Configuration object loaded by Flask from environment variables.
 
-Most operational settings are now editable at runtime from /admin/settings
-and stored in booth_settings.json on disk. Sensitive email credentials are
+Most operational settings are editable at runtime from /admin/settings and
+stored in booth_settings.json on disk. Sensitive values (SMTP password) are
 encrypted with the Flask SECRET_KEY when saved.
 
-Required environment values:
-  - APP_SECRET_KEY (used to sign sessions and encrypt stored settings)
-  - ADMIN_PASSWORD (plain-text login password)
-  - PUBLIC_BASE_URL
+Environment variables (defaults shown):
+  Required:
+    - APP_SECRET_KEY      long random string for Flask sessions and encryption
+    - ADMIN_PASSWORD      plain-text password for /admin login
+    - PUBLIC_BASE_URL     public URL customers use (e.g. https://booth.example.com)
+    - SMTP_PASS           password for the SMTP account
+  Optional:
+    - BOOTH_NAME          name in customer text and emails (default Trollgorithm Theme Songs)
+    - HOST_PORT           docker-compose host-side port mapping (default 127.0.0.1:8000)
+    - INTERNAL_PORT       gunicorn port inside the container (default 8000)
+    - MAX_REVISIONS       default customer revision limit (default 2)
+    - PRICE_PER_VERSION   price shown to customers (default 10.00)
+    - CURRENCY            currency label (default CAD)
+    - DATABASE            SQLite database path inside the container (default /app/data/booth.db)
+    - UPLOAD_FOLDER       directory for uploaded MP3s inside the container (default /app/uploads)
+    - SETTINGS_FILE       runtime settings JSON filename (default booth_settings.json)
+    - SMTP_HOST           outgoing mail server (default mailroot8.namespro.ca)
+    - SMTP_PORT           outgoing mail server port (default 465)
+    - SMTP_USER           SMTP login username (default ai@hallsworth.ca)
+    - SMTP_FROM           From address for customer emails (default ai@hallsworth.ca)
 """
 
 import os

docker-compose.yml

@@ -8,6 +8,11 @@
 # Environment variables section. The container uses them directly,
 # so no .env file is required on disk.
 #
+# Required: APP_SECRET_KEY, ADMIN_PASSWORD, SMTP_PASS, PUBLIC_BASE_URL
+# Optional: BOOTH_NAME, HOST_PORT, INTERNAL_PORT, PRICE_PER_VERSION,
+#           CURRENCY, MAX_REVISIONS, DATABASE, UPLOAD_FOLDER, SMTP_HOST,
+#           SMTP_PORT, SMTP_USER, SMTP_FROM
+#
 # Named volumes keep the SQLite database and uploaded MP3s persistent
 # across container restarts and redeploys.
 

init_db.py

@@ -6,7 +6,7 @@ Standalone script to create the SQLite database tables.
 Run this once inside the container after deployment:
     python init_db.py
 
-Or use the Flask CLI command:
+Or use the registered Flask CLI command:
     flask --app app init-db
 """
 

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.
 """
 

templates/admin/dashboard.html

@@ -10,8 +10,8 @@
   <style>
     /*
       Operator dashboard queue.
-      Shows all requests in a table, with status filters,
-      per-row Open/Delete actions, and a topbar Reset System button.
+      Shows all requests in a table with status filters, per-row Open/Delete
+      actions, a Settings link, auto-refresh hint, and logout.
     */
     body{
       font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;

templates/admin/request.html

@@ -6,9 +6,11 @@
   <title>Request #{{ req.id }} — Admin</title>
   <style>
     /*
-      Two-column admin detail page.
-      Left column: customer context + workflow.
-      Right column: operator tools + delivery.
+      Operator detail page for a single request.
+      Two-column layout:
+        left  -> customer info + internal operator notes
+        right -> Suno prompt, song upload, customer notification,
+               payment reference, and file delivery.
     */
     *{box-sizing:border-box;}
     body{

templates/admin/settings.html

@@ -7,8 +7,9 @@
   <style>
     /*
       Admin settings / maintenance page.
-      Two-column layout for revision limit, auto-refresh, SMTP config,
-      MP3 metadata defaults, database backup/restore, health stats, and reset.
+      Two-column layout for booth open/closed status, database health,
+      statistics, revision limit, auto-refresh, SMTP config,
+      MP3 metadata defaults, database backup/restore, and system reset.
     */
     :root{
       --bg:#0b0f19;

templates/player.html

@@ -7,11 +7,11 @@
   <style>
     /*
       Private customer player page.
-      Shows two audio players for Version A and Version B,
-      plus approval buttons or a revision note form.
-      After the customer makes a choice, the controls are hidden
-      and a confirmation/waiting message is shown instead.
-      The number of remaining revisions is shown when available.
+      Shows two audio players for Version A and Version B, plus approval
+      buttons or a revision note form depending on request status.
+      After the customer makes a choice, the controls are hidden and a
+      confirmation/waiting message is shown. The number of remaining
+      customer revisions is displayed when revisions are enabled.
     */
     body{
       font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;

templates/request.html

@@ -7,8 +7,9 @@
   <style>
     /*
       Customer-facing request page.
-      Designed to look fun and inviting on a convention booth tablet or phone.
-      Uses a gradient background, banner image, and a styled card form.
+      Designed for convention booth tablets/phones. Shows the banner image and
+      a styled card form for name, email, hobbies, facts, style, vocal gender,
+      and extra requests. Hidden when the booth is marked closed.
     */
     *{box-sizing:border-box;}
     body{

templates/status.html

@@ -7,7 +7,8 @@
   <style>
     /*
       Public order status lookup page.
-      Customers enter their email to see request status and the private player link.
+      Customers enter their email to see request status, approval choice,
+      and the private player link once two songs have been uploaded.
     */
     *{box-sizing:border-box;}
     body{