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.

REVIEW.md

@@ -14,6 +14,9 @@ Flask app that lets convention attendees request custom AI-generated theme songs
 - Portainer stack deployed from GitLab repo
 - SMTP (SSL port 465) for customer emails
 - Square Terminal/Reader for manual payment
+- `mutagen` for MP3 metadata tagging
+- `flask-limiter` for public form rate limiting
+- `cryptography` to encrypt the stored SMTP password
 
 ## Repository
 
@@ -24,12 +27,13 @@ Flask app that lets convention attendees request custom AI-generated theme songs
 
 | File | Notes |
 |---|---|
-| `app.py` | All routes, helpers, email function, status labels. |
+| `app.py` | All routes, helpers, email function, status labels, runtime settings, MP3 tagging, rate limiting, DB health. |
 | `config.py` | Env vars. `ADMIN_PASSWORD` is plain text. |
 | `models.py` | SQLite schema + CRUD. `player_token` is a secret URL-safe token. |
 | `init_db.py` | Run once after deploy: `python init_db.py`. |
-| `templates/admin/request.html` | Biggest template; prompt extraction JS lives here. |
-| `templates/admin/dashboard.html` | Queue table + topbar Reset System button. |
+| `templates/admin/request.html` | Biggest template; prompt copy helpers and JS live here. |
+| `templates/admin/dashboard.html` | Queue table + filters + auto-refresh + topbar Reset System button. |
+| `templates/admin/settings.html` | SMTP config, MP3 metadata defaults, DB backup/restore, health check, reset. |
 | `docker-compose.yml` | No `env_file`; variables come from Portainer. |
 
 ## Status meanings
@@ -38,12 +42,14 @@ Flask app that lets convention attendees request custom AI-generated theme songs
 pending → prompt_ready → songs_uploaded → awaiting_payment → paid → delivered
 ```
 
+`revisions_requested` is a branch used when the customer asks for changes.
+
 ## Operator workflow
 
 1. Customer fills `/request`.
-2. Open `/admin`, click request row.
-3. Click **Copy customer info for Hermes**, paste result to Hermes.
-4. Paste Hermes response (Title/Style/Lyrics format), click **Extract**, click **Save Prompt**.
+2. Open `/admin`, click request row (or filter by status).
+3. On `/admin/request/<id>`, click **Copy customer info for Hermes**, paste result to Hermes.
+4. Paste Hermes response (Title/Style/Lyrics format) into the fields and click **Save Prompt**.
 5. Copy Style/Lyrics into Suno Custom Mode, generate two versions.
 6. Upload Version A and B MP3s.
 7. Click **Send Preview Link**.
@@ -61,34 +67,23 @@ PUBLIC_BASE_URL
 BOOTH_NAME
 HOST_PORT
 INTERNAL_PORT
+MAX_REVISIONS
 ```
 
+Most can be overridden at runtime from `/admin/settings` and stored in `booth_settings.json`.
+
 ## Gotchas
 
 - Multiple forms on `admin/request.html` must stay properly closed; nested forms break buttons.
 - `upload_songs` form needs `enctype="multipart/form-data"` and a matching `</form>`.
 - The dashboard uses `basename()` as a function, not a Jinja filter.
-- Reset System deletes DB rows **and** all files under `UPLOAD_FOLDER`.
-
-## Things that could be improved later
-
-- Move customer info copy/paste to a direct Hermes API/webhook call.
-- Add operator email alerts as an opt-in config instead of hard-disabled.
-- Store admin password hashed.
-- Add a receipt/pricing page for the customer.
-- Upload progress indicator for large MP3s.
-- Back up SQLite and uploads to S3 or similar before reset.
+- Reset System deletes DB rows **and** all files under `UPLOAD_FOLDER`, then resets `sqlite_sequence`.
+- Runtime settings are stored in the persistent uploads volume (`booth_settings.json`).
+- Container cannot read host paths; all static assets used at runtime (logo, banner, favicons) must be in the repo or a mounted volume.
 
 ## How to redeploy
 
 1. Push changes to GitLab `main`.
-2. In Portainer: Stacks → `theme-song-booth` → Pull and redeploy.
-3. If schema changed, open container console and run `python init_db.py`.
+2. In Portainer: Stacks → `theme-song-booth` → **Pull and redeploy**.
+3. If schema changed, open container console and run `python init_db.py`, or use `/admin/settings` → **Fix Missing Columns**.
 
-## Last major changes
-
-- Added banner image and styling to request page.
-- Moved Reset System button to topbar next to Log out.
-- Added file/email status badges on admin request page.
-- Added per-request Delete and full-system Reset.
-- Switched Hermes prompt workflow to plain-text Title/Style/Lyrics blocks.