diff --git a/backend/app/routes/feed.py b/backend/app/routes/feed.py
index 5591ee77..7e555f11 100644
--- a/backend/app/routes/feed.py
+++ b/backend/app/routes/feed.py
@@ -41,6 +41,8 @@ VALID_STATES = {"new", "watched", "hidden"}
 # Resume-position thresholds (mirror the client): positions below this are "didn't
 # really start" and within this of the end are "basically finished" — neither is worth
 # storing, so we clear the position instead (the video shows no progress bar).
+# NB: the Plex player intentionally uses a LARGER finish margin (30s) because it marks
+# long-form items watched, not just clears a resume bar — see routes/plex/playback.py.
 PROGRESS_MIN_SECONDS = 5
 FINISH_MARGIN_SECONDS = 10
 
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index cbb7d6e2..42495705 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -158,6 +158,11 @@ def subtitle(
     return Response(subtitles.shift_vtt(vtt, offset), media_type="text/vtt")
 
 
+# Resume/watched thresholds. _PROGRESS_MIN_S matches the feed's PROGRESS_MIN_SECONDS (5), but
+# _FINISH_MARGIN_S is DELIBERATELY larger than the feed's FINISH_MARGIN_SECONDS (30 vs 10): this is
+# long-form content (movies/episodes with credits) and crossing it MARKS THE ITEM WATCHED, whereas
+# the feed's margin only clears a short video's resume bar — different domains, intentional divergence,
+# not drift. Keep them separate on purpose (see routes/feed.py).
 _PROGRESS_MIN_S = 5
 
 _FINISH_MARGIN_S = 30