docs: add POLL_INTERVAL to README, .env.sample, and .env.example

- Document background polling and on-demand mode in README
- Add POLL_INTERVAL to all config examples (Docker, Compose, .env)
- New 'Background Polling' section in Features
- Sanitize leaked credentials in .env.example

README.md

@@ -108,6 +108,7 @@ docker run -d \
   -e SABNZBD_INSTANCES='[{"name":"main","url":"http://sabnzbd:8080","apiKey":"your-key"}]' \
   -e QBITTORRENT_INSTANCES='[{"name":"main","url":"http://qbit:8080","username":"admin","password":"pass"}]' \
   -e LOG_LEVEL=info \
+  -e POLL_INTERVAL=5000 \
   docker.i3omb.com/sofarr:latest
 ```
 
@@ -130,6 +131,7 @@ services:
       - SABNZBD_INSTANCES=[{"name":"main","url":"http://sabnzbd:8080","apiKey":"your-key"}]
       - QBITTORRENT_INSTANCES=[{"name":"main","url":"http://qbit:8080","username":"admin","password":"pass"}]
       - LOG_LEVEL=info
+      - POLL_INTERVAL=5000
 ```
 
 > **Tip:** You can also use a combination — mount a `.env` file for base config, and override specific values with `-e` flags. Environment variables always take precedence.
@@ -181,6 +183,8 @@ Open `http://localhost:3001` in your browser
 ```bash
 PORT=3001                           # Server port
 LOG_LEVEL=info                      # Logging: debug, info, warn, error, silent
+POLL_INTERVAL=5000                  # Background polling interval in ms (default: 5000)
+                                    # Set to 0 or "off" to disable (on-demand mode)
 ```
 
 ### Service Instances (JSON Array Format)
@@ -231,6 +235,18 @@ To see your downloads, you need to tag your media in Sonarr/Radarr:
 
 ## Features in Detail
 
+### Background Polling
+
+sofarr polls all configured services in the background and caches the results. Dashboard requests read from cache, making them near-instant regardless of how many services you have.
+
+| Setting | Behaviour |
+|---------|----------|
+| `POLL_INTERVAL=5000` (default) | Background poller fetches every 5s. Dashboard reads from cache instantly. |
+| `POLL_INTERVAL=10000` | Poll every 10 seconds. |
+| `POLL_INTERVAL=0` / `off` / `disabled` | No background polling. Data fetched on-demand when a user opens the dashboard, then cached for 30 seconds. |
+
+**On-demand mode** is useful for low-resource setups. When one user's browser refreshes, the fetched data is cached and served to all other users until it expires. A user with a faster refresh rate effectively keeps the cache warm for everyone.
+
 ### Real-Time Updates
 - Auto-refresh every 5 seconds (configurable: 1s, 5s, 10s, or off)
 - In-place DOM updates for smooth UI (no flickering)