instrument: fix AHD DecayEnd overlay/grab defect, pin flaky curve test, close comment/doc findings

tests/test_sample_map.cpp

@@ -703,8 +703,10 @@ static void testMigratedFadeStretchesWhenTheDecodeRateDiffersFromTheProjectRate(
     CHECK(matched.trigAhd.attackFrames == 441);
     CHECK(matched.trigAhd.decayFrames == 882);
 
-    // A 44.1 kHz file opened in a 48 kHz project: 441 * 48000/44100 = 480 source frames, ~8.8%
-    // longer than the fade the saved instance actually had.
+    // resolvePlay's second argument is the DECODE rate; the seconds above were lifted (divided)
+    // at the PROJECT rate 44100 — so this is a 48 kHz file opened in a 44.1 kHz project (the
+    // mirror of component_state_io.h's worked example): 441 * 48000/44100 = 480 source frames,
+    // ~8.8% longer than the fade the saved instance actually had.
     const PlayParams stretched = resolvePlay(st, 48000);
     CHECK(stretched.trigAhd.attackFrames == 480);
     CHECK(stretched.trigAhd.decayFrames == 960);