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.

templates/admin/dashboard.html

@@ -127,6 +127,7 @@
     <!-- Status filter links -->
     <div class="filters">
       <a href="{{ url_for('admin_dashboard') }}" class="{% if current_status in (None, '') %}active{% endif %}">All</a>
+      <a href="{{ url_for('admin_dashboard', status='pending') }}" class="{% if current_status == 'pending' %}active{% endif %}">Pending</a>
       <a href="{{ url_for('admin_dashboard', status='songs_uploaded') }}" class="{% if current_status == 'songs_uploaded' %}active{% endif %}">Needs Upload</a>
       <a href="{{ url_for('admin_dashboard', status='awaiting_payment') }}" class="{% if current_status == 'awaiting_payment' %}active{% endif %}">Awaiting Payment</a>
       <a href="{{ url_for('admin_dashboard', status='delivered') }}" class="{% if current_status == 'delivered' %}active{% endif %}">Delivered</a>

templates/admin/request.html

@@ -9,10 +9,10 @@
       Single-request admin detail page.
       Sections:
         1. Customer info (with revisions note if any)
-        2. Generate Suno prompt
-        3. Upload Songs
-        4. Notify Customer
-        5. Payment & Delivery
+        2. Generate and save Suno prompt
+        3. Upload Version A and Version B MP3s
+        4. Send preview email with private player link
+        5. Mark paid and deliver selected MP3(s)
     */
     body{
       font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
@@ -154,7 +154,7 @@
 
     <!-- Section 2: Generate Suno prompt -->
     <div class="section">
-      <h2>1. Generate Suno Prompt</h2>
+      <h2>1. Generate & Save Suno Prompt</h2>
 
       <button type="button" onclick="copyPromptForHermes()">Copy customer info for Hermes</button>
       <p class="copy-hint">Paste Hermes' Title, Style, and Lyrics directly into the fields below, then save.</p>

templates/admin/settings.html

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

templates/player.html

@@ -11,6 +11,7 @@
       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.
     */
     body{
       font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
@@ -120,7 +121,7 @@
     </div>
 
     {% else %}
-    <!-- Approval form: customer picks A, B, or both -->
+    <!-- Approval form: customer picks Version A, B, or both -->
     <form method="POST" action="{{ url_for('approve', token=req.player_token) }}">
       <input type="hidden" name="choice" id="choice">
       <div class="actions">