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

src/core/instrument/engine/voice.cpp

@@ -95,6 +95,9 @@ void Voice::start(int note, int velocity, const SampleData& sample, bool declick
     // baseRatio_ source frames per output frame — needs the span converted, or a transposed
     // note's envelope outruns (or outlives) the note it shapes. Preserve reads at the source
     // rate, so its two domains already coincide.
+    // Divides by baseRatio_ alone, though the actual Varispeed read rate is baseRatio_ x
+    // envFactor — a deep pitch envelope makes this a first-order approximation, not exact.
+    // Strictly better than the un-converted source-frame span it replaced.
     const double pitchSpan =
         (pitchEngine_ == PitchEngine::Preserve || !(baseRatio_ > 0.0))
             ? static_cast<double>(postStart)
@@ -268,6 +271,9 @@ void Voice::retune(int note) {
     // legato phrase is one gesture, one strike (classic mono-synth behavior).
     if (!active_ || sample_ == nullptr) return;
     note_ = note;
+    // Changes baseRatio_ without re-converting pitchEnv_'s already-configured span (the
+    // baseRatio_ division in the note-on setup above), so a slide leaves that envelope on the
+    // first note's domain — consistent with "touch nothing else," but the drift lives here.
     baseRatio_ = keyTrackedRatio(note, sample_->rootNote, sample_->keyTrack);
     // Filter key-tracking follows the pitch: it is a function of the note, so a slide moves it
     // too. The velocity offset deliberately stays the first note's, matching velocityGain_.