No, you can't use BEGIN_HINT/END_HINT or BEGIN_SOLUTION/END_SOLUTION within BEGIN_PGML/END_PGML. The SampleProblem4 is correct that you should use BEGIN_PGML_SOLUTION/END_PGML_SOLUTION outside of the BEGIN_PGML/END_PGML block.
This is just like how you must use BEGIN_SOLUTION/END_SOLUTION outside of BEGIN_TEXT/END_TEXT. These can't be nested.
Yes, it would be nice if PGML were documented. I agree.
I never considered it to be a finished product (though it comes very close), and so hadn't written any documentation for it; but it got included into WeBWorK anyway. I guess that suggests that there is a real need for it, and people really wanted to be using it.