Update headers on today's arr-caching changes

Comment-only. Headers on the scripts touched during today's caching work
(cache-first fetches, write-through per-item cache, single-walk
consolidation, movieFile-embedded fix) still described pre-change
behavior. Also brought common.sh's top-level cache doc block current --
it was written for the single-consumer 2026-07-16 state and didn't
mention the tmpfs move, the write guard, or the 15+ consumers that now
go through it.

common.sh

@@ -2239,26 +2239,41 @@ trigger_and_await_command() {
 # ── ARR TRACKED-DATA CACHE (Lidarr, Sonarr, Radarr) ──────────────────────────────────────────
 # ==============================================================================================
 # Shared cache for each arr's tracked-library data (Lidarr artists, Sonarr series, Radarr
-# movies). Multiple scripts across all three arrs need a reasonably-current snapshot of "what
-# does this arr think it has tracked." Hitting the live API fresh every time is wasteful, and
-# during an active rescan the live number is actively misleading — tracked counts dip and
-# recover as files are detached/re-verified one by one (confirmed 2026-07-16 on Lidarr: a
-# whole-library RescanFolders made trackFileCount read 22% of normal mid-scan, which is
-# exactly the false-alarm lidarr_cleanup.sh's count-drop guard is meant to catch, but a
-# genuine rescan isn't the "something's actually wrong" case that guard exists for — the same
-# risk applies to Sonarr's RescanSeries and Radarr's RescanMovie).
+# movies). Every script across all three arrs that needs "what does this arr think it has
+# tracked" goes through this — 15+ consumers as of 2026-07-17 (all three cleanup scripts, the
+# missing-art/release-fixer/duplicate-cleanup scripts, all three playback-aware discovery
+# scripts, the TVDB/TMDb-removed checks, arr_sync.sh's local side, and the emby_to_*_sync
+# bootstrap tools). Hitting the live API fresh every time is wasteful, and during an active
+# rescan the live number is actively misleading — tracked counts dip and recover as files are
+# detached/re-verified one by one (confirmed 2026-07-16 on Lidarr: a whole-library
+# RescanFolders made trackFileCount read 22% of normal mid-scan, which is exactly the
+# false-alarm lidarr_cleanup.sh's count-drop guard is meant to catch, but a genuine rescan
+# isn't the "something's actually wrong" case that guard exists for — the same risk applies to
+# Sonarr's RescanSeries and Radarr's RescanMovie).
 #
 # Built Lidarr-only first (2026-07-16), generalized the same day to cover all three arrs —
 # identical mechanism, keyed by arr_type ("lidarr"/"sonarr"/"radarr") so each arr's cache and
 # duration history stay separate.
 #
+# Storage (2026-07-17): primary copy lives on tmpfs (ARR_CACHE_DIR) — reads/writes never touch
+# the array disk, and losing it on reboot costs nothing since a full rebuild for all three arrs
+# measures ~12s live. A persistent backup on $DATA_DIR is kept in sync by every write and gets
+# transparently restored into tmpfs by arr_cache_age_seconds() the moment it notices tmpfs is
+# missing — so a cache that was fresh before a reboot reads as fresh after too.
+#
 # Write-through: any script that already does a live library-list fetch for its own purposes
 # writes the result here as a side effect via arr_cache_write() — no dedicated polling timer
-# needed. Arrs_Stack/arr_cache_prefill.sh closes the cold-boot gap by populating all three
-# caches once at array start, before anything else needs them.
+# needed. arr_cache_write() itself refuses to write while a rescan-type command is active for
+# that arr (2026-07-17) — protects every caller uniformly, not just arr_get_tracked_data().
+# Arrs_Stack/arr_cache_prefill.sh keeps the cache warm two ways: once at array start (10min
+# wait ceiling, closes the cold-boot gap) and again every 30min via CRITICAL_MAINTENANCE_SCRIPTS
+# (1min wait ceiling — a live fetch takes seconds, not the boot-time wait).
 #
 # Consumers should call arr_get_tracked_data() — never read a cache file directly. It handles
 # the fresh/stale-no-rescan/stale-rescan-active branching so no script reimplements it.
+#
+# This is the top-level LIBRARY cache only. A separate, shorter-lived cache exists for the
+# much more expensive per-item track/episode data — see "PER-ITEM TRACKED-FILE CACHE" below.
 # ==============================================================================================
 
 # Rescan-type command names per arr — operations long/heavy enough that overlapping with one